docs: Tweak GdkSurface docs

Add more details, and refer to the GdkToplevel / GdkPopup
docs.

diff --git a/gdk/gdksurface.c b/gdk/gdksurface.c
index c32c17262b4aec4bef7cf63e2b9da4f6c531cfe3..43d3371609eec2d05d5da9507d33786f275ef2d3 100644 (file)
--- a/gdk/gdksurface.c
+++ b/gdk/gdksurface.c
@@ -55,10 +55,17 @@
  * SECTION:gdksurface
  * @Short_description: Onscreen display areas in the target window system
  * @Title: Surfaces
+ * @See_also: #GdkToplevel, #GdkPopup
  *
  * A #GdkSurface is a (usually) rectangular region on the screen.
- * It’s a low-level object, used to implement high-level objects such as
- * #GtkWindow on the GTK level.
+ * It’s a low-level object, used to implement high-level objects
+ * such as #GtkWindow or #GtkDialog in GTK.
+ *
+ * The surfaces you see in practice are either #GdkToplevel or
+ * #GdkPopup, and those interfaces provide much of the required
+ * API to interact with these surfaces. Other, more specialized
+ * surface types exist, but you will rarely interact with them
+ * directly.
  */
 
 /**